Swagger interface (OpenAPI)

Note: Access to the Swagger JSON specifications does not require authentication, and to view the contents of the live UI. But to execute any API request (with a Try it out button) you will need to authenticate first using one of the Authorize buttons, as explained below. Note that the authentication is OAuth-based authentication using PlanningSpace user credentials, the API key authentication does not grant access to the Swagger API resources.

OpenAPI, also known as Swagger, is a standard for creating specifications for REST-based APIs (see swagger.io, www.openapis.org). The PlanningSpace Web APIs use Swagger (version 2.0) to 'self-document' their API resources which means that you can access live information about the APIs in the form of either a JSON specification file, or a live help user interface.

The JSON files can be used with Swagger/OpenAPI tools that exist to work with Swagger specification files (version 2.0; the Web API Swagger files may not be compatible with OpenAPI 3.0 tools).

Swagger specification JSON file [version 16.5 Update 17 and later]

You can make API requests to each of the PlanningSpace module APIs as follows:

• PlanningSpaceDataflow/swagger/v1/swagger.json
• PlanningSpaceEconomics/swagger/v1/swagger.json
• PlanningSpaceFinancials/swagger/v1/swagger.json
• PlanningSpace/swagger/swagger/v1/swagger.json
• EconomicsCalculation/swagger/v1/swagger.json

Swagger specification JSON file [version 16.5 Update 16 and earlier]

You can make API requests to each of the PlanningSpace module APIs as follows:

• PlanningSpaceDataflow/swagger/docs/v1
• PlanningSpaceEconomics/swagger/docs/v1
• PlanningSpaceFinancials/swagger/docs/v1
• PlanningSpace/swagger/docs/v1
• EconomicsCalculation/swagger/v1/swagger.json (added in version 16.5 Update 10)

Swagger live help user interface

Important: The Swagger 'ui' interface is a live connection to a PlanningSpace tenant. The content is generated live from the tenant's API server and it can take a few seconds to appear initially. When you execute an API request with a Try it out button you are sending the request to your live API server: GET requests will return the current data content of your tenant; API requests that modify data will make immediate and permanent changes to your PlanningSpace tenant.

You can use a browser to access the Swagger UI as follows:

https://{SERVER_ADDRESS}/{TENANT}/PlanningSpaceDataflow/swagger

And similarly for the other PlanningSpace modules.

The initial view will look like the following screenshot:

Authentication for 'Try it out'

In a Swagger UI, if you want to execute any API request with a Try it out button then you will need to perform prior authentication by clicking one of the Authorize buttons which appear inside the subsections for each API operation. After clicking a button you will see a dialog Available authorizations: click the scope check box and then click the Authorize button. At this point the OAuth server may detect that you have a recently-stored login, or you may need to use the PlanningSpace interactive login screen to enter your user credentials.

After authentication, the Authorize buttons turn into Logout buttons. One authentication should remain valid for the duration of your session.

Note: When you execute an API request with a Try it out button you are sending the request to your live API server: GET requests will return the current data content of your tenant; API requests that modify data will make immediate and permanent changes to your PlanningSpace tenant.